Reorganize 'Using the issue tracker' (previously 'Issue tracker') - #1854
Reorganize 'Using the issue tracker' (previously 'Issue tracker')#1854StanFromIreland wants to merge 2 commits into
Conversation
Documentation build overview
5 files changed ·
|
| That `old bug tracker`_ was hosted under the domain ``bugs.python.org`` | ||
| (sometimes called :dfn:`bpo` or :dfn:`BPO` for short). A read-only version is | ||
| available on that domain for historical purposes. All ``bpo`` data has been | ||
| migrated to the current issue tracker on GitHub. |
There was a problem hiding this comment.
Should this also mention old issue number format, e.g. that bpo-12345 means https://bugs.python.org/issue12345 ?
| To link to a file in the repository, use a Markdown link with the path | ||
| of the file relative to the repository root, for example | ||
| ``[the os module docs](Doc/library/os.rst)``. In issues, such links | ||
| point to the latest version of the file on the default branch. In PRs, | ||
| they are resolved against the PR's branch instead, so prefer permanent | ||
| links there. |
There was a problem hiding this comment.
I don't think we need to recommend this as the one way to do it, GH's default way is quite good.
Examples from this repo:
https://github.com/python/devguide/blob/main/testing/new-buildbot-worker.rst
Permalink version:
Linking to a permalink line gives a preview:
devguide/testing/new-buildbot-worker.rst
Line 38 in 137ada6
Or a code block for multiple lines:
devguide/testing/new-buildbot-worker.rst
Lines 38 to 44 in 137ada6
There was a problem hiding this comment.
Is it satisfactory to say "either use a permalink or ..."? Explaining permalinks, beyond the link out, seems likely to balloon the text and hurt readability.
I always ask for permalinks in other projects.
There was a problem hiding this comment.
It really depends on the context. If I say "please update this file" then the main one is just file.
But if I want to refer to something specific (like some code there right now then a permalink makes more sense.
I don't think we need to explain all this stuff. More words in the devguide means less of it will be read. And it's already big :)
There was a problem hiding this comment.
Keeping it succinct is very difficult but a worthy goal.
As a full rephrase, what about this?
Links to files in the repository should either point to
mainor to a specific version of the file. In issues, a Markdown link with the path of the file relative to the repository root, for example[the os module docs](Doc/library/os.rst), will point tomain.
Use permalinks to refer to exact lines in files.
There was a problem hiding this comment.
I'd just leave this paragraph out.
4 participants
Various changes, viewing the preview will probably explain it better than I can here ;-)
The main change is splitting the page into a section for reporting new issues, and one for working with issues.